Inside Macintosh: Telephony /

Chapter 2 - Telephone Terminals

Using Telephone Terminals

You can use the Telephone Manager to open and close telephone terminals, monitor and control the physical devices associated with a telephone terminal, and manage the sound stream associated with a telephone terminal. This section describes how to perform some of these tasks.

IMPORTANT

Before you can use any of the functions that operate on telephone terminals, you need to perform the standard initialization of the Communications Toolbox and the Telephone Manager described in the chapter "Introduction to Telephony on the Macintosh."

Opening and Closing Telephone Terminals

You open a telephone terminal by calling the TELOpenTerm function, as shown on page 1-17. You pass TELOpenTerm a handle to a telephone record that specifies the tool and terminal to open. As you recall, the fields of the telephone record are filled in by a telephone tool when you call the TELNew or TELNewWithResult function. The pTELTerm field of a telephone record is a pointer to a telephone terminal record, which contains information about the telephone terminal. The telephone terminal record is defined by the TELTermRecord data type:

struct TELTermRecord {
   short                   tRef;
   TELFeatureFlags         featureFlags;
   short                   handsetSpeakerVol;
   short                   handsetMicVol;
   short                   speakerphoneVol;
   short                   speakerphoneMicVol;
   short                   ringerVol;
   short                   otherVol;
   short                   ringerTypes;
   short                   hasDisplay;
   short                   displayRows;
   short                   numDNs;
   short                   maxAllocCA;
   short                   curAllocCA;
   short                   builtinSpeakerVol;
   short                   builtinSpeakerMicVol;
   long                    reserved;
};
typedef struct TELTermRecord TELTermRecord;
typedef TELTermRecord *TELTermPtr;

As you can see, a telephone terminal record contains information about the capabilities of a particular telephone terminal, such as the volume of the handset speaker and the number of rows of text the display is able to show. In general, you should use Telephone Manager functions to access the information in a telephone terminal record rather than access the fields of that record directly. For instance, to get the volume of the handset speaker, you can call the TELGetVolume function; see page 2-24 for details.

When you're done using a particular telephone terminal, you can close it by calling the TELCloseTerm function, as follows:

myErr = TELCloseTerm(myTerm);

Closing a terminal removes any connection between the terminal and your application. If no other application has opened that terminal, the terminal's device driver is closed.

Getting Terminal Features

The featureFlags field of a telephone terminal record is a bit field whose bits encode information about the capabilities and features available for a telephone terminal. The meanings of the bits in that field are defined by these feature flags:

enum {
   pcmAvail                = 1L << 0,
   hasHandset              = 1L << 1,
   hasSpeakerphone         = 1L << 2,
   canOnHookDial           = 1L << 3,
   hasRinger               = 1L << 4,
   canSetDisplay           = 1L << 5,
   hasKeypad               = 1L << 6,
   hasVideo                = 1L << 7,
   hasOther                = 1L << 8,
   crossDNConference       = 1L << 9,
   hasSubaddress           = 1L << 10,
   hasUserUserInfo         = 1L << 11,
   hasHandsetSoundStreams  = 1L << 12,
   hasIndHandset           = 1L << 13,
   hasBuiltinSpeakerphone  = 1L << 14
};

For instance, if the hasIndHandset bit is set, the associated telephone terminal has a handset that can be used as an independent handset. In most cases, when a telephone handset is taken off hook, it is automatically connected to a telephone line (that is, the receiver gets a dial tone). In some cases, however, such as when the computer's microphone and speaker are used as a built-in speaker phone, the handset can be used as an independent sound I/O device, referred to as an independent handset.

You can determine whether a particular telephone terminal has an independent handset by calling the MyTermHasIndHandset function defined in Listing 2-1.

Listing 2-1 Checking for an independent handset

Boolean MyTermHasIndHandset (TELHandle myTerm)
{
   TELErr      myErr;
   Boolean     myHasIndHS = false;

   myErr = TELGetInfo(myTerm);      //update featureFlags field
   if (myErr != noErr) {
      TELDispose(myTerm);           //dispose of invalid terminal
   } else {
       myHasIndHS = 
               ((*(**myTerm).pTELTerm).featureFlags & hasIndHandset);
   }
   return(myHasIndHS);
}

As you can see, MyTermHasIndHandset calls the TELGetInfo function to update the current feature flags of the specified telephone terminal. Then it checks to see whether the hasIndHandset bit is set. If so, the terminal has an independent handset.

You can use a similar technique to read any of the other terminal settings. See "Telephone Terminal Feature Flags," beginning on page 2-8 for a complete description of all the terminal feature flags.